Crate yubikey[−][src]
Expand description
yubikey.rs: pure Rust cross-platform host-side driver for YubiKey
devices from Yubico using the Personal Computer/Smart Card (PC/SC)
interface as provided by the pcsc crate.
Features
Personal Identity Verification (PIV)
PIV is a NIST standard for both signing and encryption using SmartCards and SmartCard-based hardware tokens like YubiKeys.
PIV-related functionality can be found in the piv module.
This library natively implements the protocol used to manage and utilize PIV encryption and signing keys which can be generated, imported, and stored on YubiKey devices.
See Yubico’s guide to PIV-enabled YubiKeys for more information on which devices support PIV and the available functionality.
Minimum Supported Rust Version
Rust 1.51 or newer.
Supported YubiKeys
NOTE: Nano and USB-C variants of the above are also supported. Pre-YK4 YubiKey NEO series is NOT supported.
Supported Operating Systems
- Linux
- macOS
- Windows
Supported Algorithms
- Authentication:
3DES - Encryption:
- RSA:
RSA1024,RSA2048 - ECC:
ECCP256,ECCP384(NIST curves: P-256, P-384)
- RSA:
- Signatures:
- RSASSA-PKCS#1v1.5:
RSA1024,RSA2048 - ECDSA:
ECCP256,ECCP384(NIST curves: P-256, P-384)
- RSASSA-PKCS#1v1.5:
NOTE: RSASSA-PSS signatures and RSA-OAEP encryption may be supportable (TBD)
Status
Functionality which has been successfully tested is available by default.
Any functionality which is gated on the untested feature has not been
properly tested and is not known to function correctly.
Please see the untested functionality tracking issue for current status.
We would appreciate any help testing this functionality and removing the
untested gating as well as writing more automated tests.
History
This library is a Rust translation of the yubico-piv-tool utility by Yubico, which was originally written in C. It was mechanically translated from C into Rust using Corrode, and then subsequently heavily refactored into safer, more idiomatic Rust.
For more information on yubico-piv-tool and background information on how the YubiKey implementation of PIV works in general, see the Yubico PIV Tool Command Line Guide.
Security Warning
No security audits of this crate have ever been performed. Presently it is in an experimental stage and may still contain high-severity issues.
USE AT YOUR OWN RISK!
Code of Conduct
We abide by the Contributor Covenant and ask that you do as well.
For more information, please see CODE_OF_CONDUCT.md.
License
yubikey.rs is a fork of and originally a mechanical translation from Yubico’s yubico-piv-tool, a C library/CLI program.
The original library was licensed under a 2-Clause BSD License, which this library inherits as a derived work.
Re-exports
Modules
X.509 certificate support.
Personal Identity Verification (PIV) cryptographic keys stored in a YubiKey.
Support for enumerating available PC/SC card readers.
Structs
Cardholder Capability Container (CCC) Identifier Card ID.
Cardholder Capability Container (CCC) Identifier.
Cardholder Unique Identifier (CHUID).
YubiKey configuration.
Management Key (MGM).
untestedMS Container Map records.
untestedPKCS#7-formatted certificate store for enterprise trust roots.
YubiKey serial number.
Setting booleans: configuration values sourced from a file or the environment.
A Universally Unique Identifier (UUID).
YubiKey version.
YubiKey device: primary API for opening a session and performing various operations.
Enums
Kinds of errors.
Management Key (MGM) key types (manual/derived/protected).
Specifies how often the PIN needs to be entered for access to the credential in a given slot.
Source of how a setting was configured.
Specifies under what conditions a physical touch on the metal contact is required, in
addition to the PinPolicy.